JSON_SERIALIZE

The JSON_SERIALIZE function takes a HASH, LIST, or structure variable and converts it into a JSON (JavaScript Object Notation) string.

This routine is written in the IDL language. Its source code can be found in the file json_serialize.pro in the lib subdirectory of the IDL distribution.

Tip: The JSON_SERIALIZE converts a LIST or HASH into raw JSON with no "pretty" printing. If you want to output prettified JSON (with appropriate indenting and line breaks), you can simply bypass JSON_SERIALIZE and print out your LIST or HASH using Implied Print.

Examples

Convert a LIST of IDL values into a JSON string

mylist = LIST(!TRUE, !NULL, 42, 3.14, "Hello")

json = JSON_SERIALIZE(mylist)

PRINT, json

IDL prints:

[true,null,42,3.14,"Hello"]

Convert a HASH of key-value pairs into a JSON string

myhash = HASH("Planet", "Jupiter", "Index", 5, "Mass", 1.9d27, "Units", "kg")

json = JSON_SERIALIZE(myhash)

PRINT, json

IDL prints:

{"Planet":"Jupiter","Index":5,"Units":"kg","Mass":1.9e27}

Convert an IDL structure into a JSON string

struct = {PLANET: "Jupiter", INDEX: 5, MASS: 1.9d27, UNITS: "kg"}

json = JSON_SERIALIZE(struct)

PRINT, json

IDL prints:

{"PLANET":"Jupiter","INDEX":5,"MASS":1.9e27,"UNITS":"kg"}

Syntax

Result = JSON_SERIALIZE(Value, /LOWERCASE)

Return Value

The result is a string containing the JSON string. If the input value is a LIST, then the JSON string will be encoded as a JSON array, with square brackets and comma-separated values. If the input value is a HASH, then the JSON string will be encoded as a JSON object, with curly braces and key-value pairs.

When converting IDL variables, the following rules are used:

• Undefined variables (or !NULL) become "null".
• Boolean variables are passed on as "true" or "false".
• All bytes and integers are passed on unchanged (if these are converted back using JSON_PARSE, they will be type LONG64).
• All floating-point numbers are passed on unchanged (if these are converted back using JSON_PARSE, they will be type DOUBLE).
• All strings are surrounded by double-quotes. The following special characters will be escaped: \\ (backslash), \" (double quote), \b (backspace 8b), \f (form feed 12b), \n (line feed 10b), \r (carriage return 13b), \t (tab 9b). Note that forward slash characters are not escaped - this allows URL's to still look normal in the resulting JSON. Also note that the string "!NULL" is a special case, and will be converted into the "null" value.
• LIST values become JSON arrays, with each list element being converted using the above rules.
• Structure tagname-value pairs become JSON objects, with each value being converted using the above rules. You can use the LOWERCASE keyword to change the tagnames to lowercase.
• HASH key-value pairs become JSON objects, with each value being converted using the above rules.

Note: Since the HASH stores its key-value pairs in an arbitrary order, the key-value pairs in the resulting JSON string may be in a different order than the order in which the keys were added to the hash.

Arguments

Value

Value must be a HASH, LIST, or structure variable.

Keywords

LOWERCASE

By default, when serializing an IDL structure, all of the structure tag names are in uppercase within the resulting JSON string. Set the LOWERCASE keyword to use lowercase for the structure tag names.

Version History

Resources and References

JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write, and for machines to parse and generate. JSON was designed as an alternative to XML, and is based on a subset of the JavaScript Programming Language, Standard ECMA-262 3rd Edition - December 1999. Further details can be found at http://www.json.org.

See Also

JSON_PARSE, HASH, LIST, IDLnetURL